Upload a Creative

IQM’s REST API enables you to interact with most of our platform's applications.

The following endpoints will be used to upload a Creative:

POST /api/v3/ua/login
GET /api/v3/master/creativeTypes
POST /api/v3/crt/creatives
GET /api/v3/crt/creatives/{creativeId}

About IQM Creatives

The IQM APIs provide access to upload a Creative in Image, Video, Audio, HTML, XLSX, or CSV formats. The APIs can be used to connect to the desired applications.

More resources:

• Creatives and Specifications Help Center Article
• Creative API Guidelines

Before You Begin

To upload a Creative and create a Campaign, the following are required:

1. An Account On the IQM Platform
   • See Getting Started section to create an account and request a Client ID and Client Secret
2. Image, Video, Audio, HTML, VAST, DAAST, CSV, or XLSX File to Upload Creative

info

File requirements for Creative file:

• 2MB for JPG, JPEG, PNG
• 750KB for GIF
• 400MB for MOV, MP4
• 100MB for MP3, WAV, OGG, MPEG

For more information on VAST and DAAST XML format specifications, please see IAB Tech Lab's Documentation.

Sample CSV file: https://app.iqm.com/creatives/example-files/sample_html_creatives.csv

Authentication

Use the following header parameters for all requests after logging in:

Headers
Authentication string required	Authentication bearer token See Authentication Guide
X-IAA-OW-ID integer required	Organization Workspace ID Header

Upload a Creative Using the IQM API

This Quickstart Guide will cover how to create a Campaign and upload a Creative.

The minimum requirements to perform this task are: logging in with authentication credentials, uploading a Creative, and creating a Campaign. Once these steps are accomplished, more can be learned about IQM's API through the Guidelines pages.

1. Log In
   • Optional if you have already logged in and have a token
2. Request Creative Types
   • Optional if you already know supported/desired types
3. Upload Creative File
4. Check Creative Status

Step 1: Log in

POST /api/v3/ua/login

To log in, the Authentication: Basic header is required. The Login API returns an OAuth-compliant response with an Organization Workspace ID (owId), a unique identifier for each Organization. This ID will be used for any further API communications.

For further information see the complete Login API Documentation.

Headers
Authentication string required	Authentication bearer token See Authentication Guide
X-IAA-HOST string required	Workspace URL

Request Schema
grantType string required	OAuth Grant Types
email string required	User account email
password string required	User account password

JSON

Request Schema

{
  "grantType": "password",
  "email": "pratik.t+ihp@iqm.com",
  "password": "123456"
}

Response 200

{
  "success": true,
  "data":
  {
    "access_token": "106adb25-37b0-4cab-8381-d682fe7cc3c8",
    "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64",
    "scope": "read write",
    "token_type": "bearer",
    "expires_in": 35999,
    "owId": 200001
  }
}

More Responses

Response 400

{
   "success": false,
   "data":
   {
      "status": "On Hold",
      "reason": "The particular account is kept on hold due to missed payment dates for last 3 months.",
      "supportEmail": "support@iqm.com"
   },
   "errorObjects":
   [
      {
         "error": "User is not allowed to access provided customer",
         "reason": "User is not associated with any active organization."
      }
   ]
}

Response 403

{
   "success": false,
   "errorObjects":
   [
      {
         "error": "User doesn't exist or user is not allowed to provided workspace."
      }
   ]
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          access_token: string;
          refresh_token: string;
          scope: string;
          token_type: string;
          expires_in: number;
          owId: number;
        };
      };
    };
  };
  400: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          status: string;
          reason: string;
          supportEmail: string;
        };
        errorObjects: {
          error: string;
          reason: string;
        }[];
      };
    };
  };
  403: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      };
    };
  };
};

function Login(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/login',
    requestBody: {
      content: {
        "application/json": {
          email: `string`,
          password: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Step 2: Request Creative Types

GET /api/v3/master/creativeTypes

To upload a Creative, a Creative Type must be provided. Use the Creative Type list endpoint to request a full list of allowed Creative Types.

For further information see the complete Creative Types API Documentation.

JSON

Response 200

{
  "success": true,
  "data": {
    "data": [
      {
        "id": 17,
        "name": "Audio",
        "rtbTypeId": 2
      },
      {
        "id": 15,
        "name": "Native",
        "rtbTypeId": 4
      },
      {
        "id": 14,
        "name": "Video",
        "rtbTypeId": 3
      },
      {
        "id": 13,
        "name": "HTML",
        "rtbTypeId": 1
      },
      {
        "id": 11,
        "name": "Image",
        "rtbTypeId": 1
      }
    ],
    "totalRecords": 5,
    "filteredRecords": 5
  }
}

More Responses

Response 500

{
  "statusCode": 500,
  "responseObject": {
    "errorMsg": "Internal server error",
    "errorCode": 500
  }
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          label: string;
          rtbTypeId: string;
        }[];
        totalRecords: number;
        filteredRecords: number;
      }
    };
  };
};

function getCreativeTypes_1(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/master/creativeTypes',
    params: {
      query?: {
        creativeTypeIds?: `string`,
        ids?: `string`,
        pageNo?: `number`,
        noOfEntries?: `number`,
        sortBy?: `string`,
        order?: `string`,
        searchField?: `string`
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Step 3: Upload a Creative

POST /api/v3/crt/creatives

Once you have the desired Creative Type ID, you can upload a Creative. With the two query parameters, creativeRequest and creativeFiles, you will add the Creative details and the Creative file respectively.

creativeRequest maps a UUID to fields defining the Creative details outlined in the table below and shown as an example in the Query Sample code block in the right-hand column.

creativeFiles are added as multipart format. See the MDN Documentation on Multipart/form-data encoding for more information.

Query Parameters
creativeRequest string required	This parameter accepts a Map of UUIDs to Creative details. Each UUID corresponds to a single Creative.
creativeFiles string	Array of Creative files uploaded as multipart files. These files will be used for creating the Creatives. Each file is processed according to its type (image, video, etc.)

creativeRequest Fields
creativeName string	Creative name
platformCreativeTypeId string	Creative type ID
creativeSourceType string	Creative source type Supported values: HTML, FILE, URL
creativeSource string	Creative source
imageDetails object	Image details
imageDetails object properties creativeWidth integer Creative width (px) creativeHeight integer Creative height (px)

JSON

Query Sample

https://app.iqm.com/api/v3/crt/creatives?creativeRequest={"840ab4ef-0e10-42eb-9683-ae9692ed5c9a":{"creativeName":"IQM-LOGO","platformCreativeTypeId":11,"clickUrl":"https://iqm.com/","creativeSource":"https://d3jme5si7t6llb.cloudfront.net/assets/203578/r6j1sV3_1748555808865.png","creativeSourceType":"URL","imageDetails":{"creativeWidth":1024,"creativeHeight":512}}}

Response 200

{
  "success": true,
  "data": {
    "successData": {
      "PS": "701388"
    },
    "failedData": {
      "PF": "Creative file missing. Please attach the required file. : null"
    }
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          successData: {
            PS: string;
          };
          failedData: {
            PF: string;
          }
        }
      };
    };
  };
}

function createCreatives(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/crt/creatives',
    params: {
      query: {
        creativeRequest: `string`,
        creativeFiles?: `array of strings`
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Step 4: Check Creative Status

GET /api/v3/crt/creatives/{creativeId}

This API checks a Creative's status. Use the creativeId (6 digit number under data parameter in response) retrieved from the previous step to get its details.

The Creative details endpoint returns a Status ID (highlighted in code sample). A status ID of 2 means the Creative is running.

Path Parameter
creativeId array of integers	Creative ID

JSON

Response 200

{
  "success": true,
  "data": {
    "creativeId": 686855,
    "creativeName": "300x600-w23-01",
    "rtbCreativeTypeId": 1,
    "platformCreativeTypeId": 11,
    "creativeStatusId": 2,
    "creativeSource": "https://d3jme5si7t6llb.cloudfront.net/image/202760/efk0sUk_1730201855013.jpg",
    "creativeCardSource": "https://d3jme5si7t6llb.cloudfront.net/Screenshots/202760/278x220/efk0sUk_1730201855013.jpg",
    "clickUrl": "http://iqm.com",
    "imageDetails": {
      "pixelUrl": "http://pixel.com",
      "creativeWidth": 300,
      "creativeHeight": 600
    },
    "creativeSourceType": "file",
    "creativePreviewFlag": 1,
    "createdAt": 1730201855165,
    "modifiedAt": "2024-10-29T06:10:15.000+00:00",
    "userDetails": {
      "uowId": 175891,
      "userName": "Hardik",
      "userEmail": "hardik.v+iqmsuper@iqm.com",
      "hasApprovalAccess": true,
      "hasEditAccess": true
    },
    "organizationDetails": {
      "owId": 202760,
      "organizationName": "AdWing"
    }
  }
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          creativeId: number;
          creativeName: string;
          rtbCreativeTypeId: number;
          platformCreativeTypeId: number;
          creativeStatusId: number;
          creativeSource: string;
          creativeCardSource: string;
          clickUrl: string;
          imageDetails: {
            pixelUrl: string;
            creativeWidth: number;
            creativeHeight: number;
          };
          creativeSourceType: string;
          creativePreviewFlag: number;
          createdAt: number;
          modifiedAt: number;
          userDetails: {
            uowId: number;
            userName: string;
            userEmail: string;
            hasApprovalAccess: boolean;
            hasEditAccess: boolean;
          };
          organizationDetails: {
            owId: number;
            organizationName: string
          }
        }
      };
    };
  };
}

function getCreative(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/crt/creatives/{creativeId}',
    params: {
      path: {
        creativeId: `number`
      }
    }
  };